docs(adr): specify Promptfoo grading output contract - #1649

Summary

The Promptfoo alignment docs now separate authored YAML compatibility from AgentV's canonical result artifacts. ADR 0017 specifies the major-version public grading.json contract as aggregate pass/score/reason plus always-present graders[] and nested checks[], while explicitly rejecting legacy public aliases such as assertion_results, assertions, passed-only, top-level checks, and dynamic single-grader shapes.

This also records why Promptfoo's export/internal result format is inspiration rather than AgentV's artifact contract: AgentV borrows the clean aggregate grading vocabulary and component-breakdown idea, then keeps the filesystem/Git-native split run bundle as the source of truth. Summary and index guidance now prefers pass_rate, pass_count, sample_count, and passed/pass_any, reserving pass_at_k for true sampling metrics with a real k.

The older restructure plan is marked as historical for the stale grading/pass@k sections, and the review-summary plan now states that Beads are the implementation source of truth while PRs and plans summarize them for review.

Scope

• Updates ADR/spec and plan text only.
• Does not implement run-artifact writers, Dashboard readers, SDK schemas, parser behavior, or grader execution changes.
• Leaves av-kfik.28.2 through av-kfik.28.7 open for the sequenced implementation work.

Validation

• bun install to hydrate the worktree dependencies; no lockfile changes.
• bun run lint.
• git diff --check.
• Local markdown link check not run: CI uses lychee-action, and no lychee binary is installed in this worktree.
• Dedicated CE subagent review skipped because this session did not authorize delegation; performed a manual contract/diff review instead.

Post-Deploy Monitoring & Validation

No additional operational monitoring required. This is a docs/ADR/spec-only change and has no runtime, deploy, API, CLI, artifact-writer, or Dashboard behavior.

Related

Related: av-kfik.28.1.